<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Adding Components to a Page Using HTML Tags - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level3"><a href="bnarb.html">Setting Up a Page</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3"><a href="">Adding Components to a Page Using HTML Tags</a></p>
<p class="toc level4"><a href="#bnarg">Common Component Tag Attributes</a></p>
<p class="toc level5"><a href="#bnarh">The <tt>id</tt> Attribute</a></p>
<p class="toc level5"><a href="#bnari">The <tt>immediate</tt> Attribute</a></p>
<p class="toc level5"><a href="#bnarj">The <tt>rendered</tt> Attribute</a></p>
<p class="toc level5"><a href="#bnark">The <tt>style</tt> and <tt>styleClass</tt> Attributes</a></p>
<p class="toc level5"><a href="#bnarl">The <tt>value</tt> and <tt>binding</tt> Attributes</a></p>
<p class="toc level4 tocsp"><a href="#gjdgq">Adding HTML Head and Body Tags</a></p>
<p class="toc level4"><a href="#bnarm">Adding a Form Component</a></p>
<p class="toc level4"><a href="#bnaro">Using Text Components</a></p>
<p class="toc level5"><a href="#bnarr">Rendering a Text Field with the <tt>h:inputText</tt> Tag</a></p>
<p class="toc level5"><a href="#bnarv">Rendering a Password Field with the <tt>h:inputSecret</tt> Tag</a></p>
<p class="toc level5"><a href="#bnars">Rendering a Label with the <tt>h:outputLabel</tt> Tag</a></p>
<p class="toc level5"><a href="#bnart">Rendering a Hyperlink with the <tt>h:outputLink</tt> Tag</a></p>
<p class="toc level5"><a href="#bnaru">Displaying a Formatted Message with the <tt>h:outputFormat</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="#bnarw">Using Command Component Tags for Performing Actions and Navigation</a></p>
<p class="toc level5"><a href="#bnarx">Rendering a Button with the <tt>h:commandButton</tt> Tag</a></p>
<p class="toc level5"><a href="#gkbuj">Rendering a Hyperlink with the <tt>h:commandLink</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="#bnasb">Adding Graphics and Images with the <tt>h:graphicImage</tt> Tag</a></p>
<p class="toc level4"><a href="#bnasc">Laying Out Components with the <tt>h:panelGrid</tt> and <tt>h:panelGroup</tt> Tags</a></p>
<p class="toc level4"><a href="#bnase">Displaying Components for Selecting One Value</a></p>
<p class="toc level5"><a href="#bnasg">Displaying a Check Box Using the <tt>h:selectBooleanCheckbox</tt> Tag</a></p>
<p class="toc level5"><a href="#bnash">Displaying a Menu Using the <tt>h:selectOneMenu</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="#bnasi">Displaying Components for Selecting Multiple Values</a></p>
<p class="toc level4"><a href="#bnask">Using the <tt>f:selectItem</tt> and <tt>f:selectItems</tt> Tags</a></p>
<p class="toc level5"><a href="#bnasm">Using the <tt>f:selectItems</tt> Tag</a></p>
<p class="toc level5"><a href="#bnasn">Using the <tt>f:selectItem</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="#bnarz">Using Data-Bound Table Components</a></p>
<p class="toc level4"><a href="#bnaso">Displaying Error Messages with the <tt>h:message</tt> and <tt>h:messages</tt> Tags</a></p>
<p class="toc level4"><a href="#giqzd">Creating Bookmarkable URLs with the <tt>h:button</tt> and <tt>h:link</tt> Tags</a></p>
<p class="toc level4"><a href="#giqwq">Using View Parameters to Configure Bookmarkable URLs</a></p>
<p class="toc level4"><a href="#gjgep">Resource Relocation Using <tt>h:output</tt> Tags</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnarc.html">Using Core Tags</a></p>
<p class="toc level2 tocsp"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="bnarb.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="bnarc.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnarf"></a><h2>Adding Components to a Page Using HTML Tags</h2>
<a name="indexterm-274"></a><p>The tags defined by the JavaServer Faces standard HTML tag library represent HTML
form components and other basic HTML elements. These components display data or accept
data from the user. This data is collected as part of a
form and is submitted to the server, usually when the user clicks a
button. This section explains how to use each of the component tags shown
in <a href="#bnaqh">Table&nbsp;7-1</a>.</p>

<a name="bnaqh"></a><p class="caption">Table&nbsp;7-1 The Component Tags</p><table><col width="26%"><col width="28%"><col width="24%"><col width="20%"><tr><th align="left" valign="top" scope="column"><p>Tag</p>

</th>
<th align="left" valign="top" scope="column"><p>Functions</p>

</th>
<th align="left" valign="top" scope="column"><p>Rendered as</p>

</th>
<th align="left" valign="top" scope="column"><p>Appearance</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-275"></a><tt>column</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Represents a column of data in a data component</p>

</td>
<td align="left" valign="top" scope="row"><p>A column
of data in an HTML table</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-276"></a>A column in a table</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-277"></a><tt>commandButton</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Submits a form
to the application</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;input type=type></tt> element, where the <tt>type</tt> value can be
<tt>submit</tt>, <tt>reset</tt>, or <tt>image</tt></p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-278"></a>A button</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-279"></a><tt>commandLink</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Links to another page or location on a page</p>

</td>
<td align="left" valign="top" scope="row"><p>An
HTML <tt>&lt;a href></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-280"></a>A hyperlink</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-281"></a><tt>dataTable</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Represents a data wrapper</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;table></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-282"></a>A table that
can be updated dynamically</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-283"></a><tt>form</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Represents an input form (inner tags of the form
receive the data that will be submitted with the form)</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;form></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p>No
appearance</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-284"></a><tt>graphicImage</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays an image</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;img></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p>An image</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-285"></a><tt>inputHidden</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a page author to include
a hidden variable in a page</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;input type=hidden></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-286"></a>No appearance</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-287"></a><tt>inputSecret</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a user
to input a string without the actual string appearing in the field</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML
<tt>&lt;input type=password></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-288"></a>A text field, which displays a row of characters instead of
the actual string entered</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-289"></a><tt>inputText</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a user to input a string</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;input type=text></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-290"></a>A
text field</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-291"></a><tt>inputTextarea</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a user to enter a multiline string</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;textarea></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-292"></a>A
multi-row text field</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-293"></a><tt>message</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays a localized message</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;span></tt> tag if styles are
used</p>

</td>
<td align="left" valign="top" scope="row"><p>A text string</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-294"></a><tt>messages</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays localized messages</p>

</td>
<td align="left" valign="top" scope="row"><p>A set of HTML <tt>&lt;span></tt> tags if styles
are used</p>

</td>
<td align="left" valign="top" scope="row"><p>A text string</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-295"></a><tt>outputFormat</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays a localized message</p>

</td>
<td align="left" valign="top" scope="row"><p>Plain text</p>

</td>
<td align="left" valign="top" scope="row"><p>Plain text</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-296"></a><tt>outputLabel</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays a nested component
as a label for a specified input field</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;label></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-297"></a>Plain text</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-298"></a><tt>outputLink</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Links
to another page or location on a page without generating an action event</p>

</td>
<td align="left" valign="top" scope="row"><p>An
HTML <tt>&lt;a></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p>A hyperlink</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-299"></a><tt>outputText</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays a line of text</p>

</td>
<td align="left" valign="top" scope="row"><p>Plain text</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-300"></a>Plain text</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-301"></a><tt>panelGrid</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays a table</p>

</td>
<td align="left" valign="top" scope="row"><p>An
HTML <tt>&lt;table></tt> element with <tt>&lt;tr></tt> and <tt>&lt;td></tt> elements</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-302"></a>A table</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-303"></a><tt>panelGroup</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Groups a set of
components under one parent</p>

</td>
<td align="left" valign="top" scope="row"><p>A HTML <tt>&lt;div></tt> or <tt>&lt;span></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p>A row in a
table</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-304"></a><tt>selectBooleanCheckbox</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a user to change the value of a Boolean choice</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML
<tt>&lt;input type=checkbox></tt> element.</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-305"></a>A check box</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-306"></a><tt>selectItem</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Represents one item in a list of items from
which the user must select one</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;option></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p>No appearance</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-307"></a><tt>selectItems</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Represents a list of
items from which the user must select one</p>

</td>
<td align="left" valign="top" scope="row"><p>A list of HTML <tt>&lt;option></tt>
elements</p>

</td>
<td align="left" valign="top" scope="row"><p>No appearance</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-308"></a><tt>selectManyCheckbox</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays a set of check boxes from which the user can
select multiple values</p>

</td>
<td align="left" valign="top" scope="row"><p>A set of HTML <tt>&lt;input></tt> elements of type <tt>checkbox</tt></p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-309"></a>A set of
check boxes</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-310"></a><tt>selectManyListbox</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a user to select multiple items from a set of
items, all displayed at once</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;select></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-311"></a>A list box</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-312"></a><tt>selectManyMenu</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a user to
select multiple items from a set of items</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;select></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-313"></a>A scrollable
combo box</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-314"></a><tt>selectOneListbox</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a user to select one item from a set of
items, all displayed at once</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;select></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-315"></a>A list box</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-316"></a><tt>selectOneMenu</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a user to
select one item from a set of items</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;select></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-317"></a>A scrollable
combo box</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-318"></a><tt>selectOneRadio</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a user to select one item from a set of
items</p>

</td>
<td align="left" valign="top" scope="row"><p>An HTML <tt>&lt;input type=radio></tt> element</p>

</td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-319"></a>A set of radio buttons</p>

</td>
</tr>
</table><p>The next section explains the  important tag attributes that are common to
most component tags. For each of the components discussed in the following sections,
<a href="bnaty.html">Writing Bean Properties</a> explains how to write a bean property bound to a particular component
or its value.</p>



<a name="bnarg"></a><h3>Common Component Tag Attributes</h3>
<a name="indexterm-320"></a><a name="indexterm-321"></a><a name="indexterm-322"></a><p>Most of the component tags support the attributes shown in <a href="#gkcks">Table&nbsp;7-2</a>.</p>

<a name="gkcks"></a><p class="caption">Table&nbsp;7-2 Common Component Tag Attributes</p><table><col width="24%"><col width="75%"><tr><th align="left" valign="top" scope="column"><p>Attribute</p>

</th>
<th align="left" valign="top" scope="column"><p>Description</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-323"></a><tt>binding</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Identifies a
bean property and binds the component instance to it.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-324"></a><tt>id</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Uniquely identifies the component.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-325"></a><tt>immediate</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>If
set to <tt>true</tt>, indicates that any events, validation, and conversion associated with the
component should happen when request parameter values are applied,</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-326"></a><tt>rendered</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Specifies a condition under which
the component should be rendered. If the condition is not satisfied, the component
is not rendered.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-327"></a><tt>style</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Specifies a Cascading Style Sheet (CSS) style for the tag.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-328"></a><tt>styleClass</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Specifies
a CSS class that contains definitions of the styles.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-329"></a><tt>value</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Identifies an external data
source and binds the component&rsquo;s value to it.</p>

</td>
</tr>
</table><p>All the tag attributes (except <tt>id</tt>) can accept expressions, as defined by the
EL, described in <a href="gjddd.html">Chapter&nbsp;6, Expression Language</a>.</p>



<a name="bnarh"></a><h4>The <tt>id</tt> Attribute</h4>
<p><a name="indexterm-330"></a>The <tt>id</tt> attribute is not usually required for a component tag but is
used when another component or a server-side class must refer to the component.
If you don&rsquo;t include an <tt>id</tt> attribute, the JavaServer Faces implementation automatically generates a
component ID. Unlike most other JavaServer Faces tag attributes, the <tt>id</tt> attribute takes
expressions using only the evaluation syntax described in <a href="#bnari">The <tt>immediate</tt> Attribute</a>, which uses the <tt>${}</tt> delimiters.
For more information on expression syntax, see <a href="bnahu.html#bnahv">Value Expressions</a>.</p>



<a name="bnari"></a><h4>The <tt>immediate</tt> Attribute</h4>
<a name="indexterm-331"></a><p>Input components and command components (those that implement the <tt>ActionSource</tt> interface, such
as buttons and hyperlinks) can set the <tt>immediate</tt> attribute to <tt>true</tt> to force events,
validations, and conversions to be processed when request parameter values are applied.</p>

<p>You need to carefully consider how the combination of an input component&rsquo;s
<tt>immediate</tt> value and a command component&rsquo;s <tt>immediate</tt> value determines what happens when the
command component is activated.</p>

<p>Assume that you have a page with a button and a field
for entering the quantity of a book in a shopping cart. If the
<tt>immediate</tt> attributes of both the button and the field are set to <tt>true</tt>,
the new value entered in the field will be available for any processing
associated with the event that is generated when the button is clicked. The
event associated with the button as well as the event validation and conversion
associated with the field are all handled when request parameter values are applied.</p>

<p>If the button&rsquo;s <tt>immediate</tt> attribute is set to <tt>true</tt> but the field&rsquo;s <tt>immediate</tt>
attribute is set to <tt>false</tt>, the event associated with the button is processed without
updating the field&rsquo;s local value to the model layer. The reason is that
any events, conversion, or validation associated with the field occurs <b>after</b> request parameter
values are applied.</p>



<a name="bnarj"></a><h4>The <tt>rendered</tt> Attribute</h4>
<a name="indexterm-332"></a><p>A component tag uses a Boolean EL expression along with the <tt>rendered</tt>
attribute to determine whether the component will be rendered. For example, the <tt>commandLink</tt>
component in the following section of a page is not rendered if the
cart contains no items:</p>

<pre>&lt;h:commandLink id="check"
    ...
    rendered="#{cart.numberOfItems > 0}">
    &lt;h:outputText
        value="#{bundle.CartCheck}"/>
&lt;/h:commandLink></pre><p>Unlike nearly every other JavaServer Faces tag attribute, the <tt>rendered</tt> attribute is
restricted to using rvalue expressions. As explained in <a href="bnahu.html">Value and Method Expressions</a>, these rvalue expressions can only
read data; they cannot write the data back to the data source. Therefore,
expressions used with <tt>rendered</tt> attributes can use the arithmetic operators and literals that
rvalue expressions can use but lvalue expressions cannot use. For example, the expression
in the preceding example uses the <tt>></tt> operator.</p>



<a name="bnark"></a><h4>The <tt>style</tt> and <tt>styleClass</tt> Attributes</h4>
<a name="indexterm-333"></a><a name="indexterm-334"></a><p>The <tt>style</tt> and <tt>styleClass</tt> attributes allow you to specify CSS styles for the
rendered output of your tags. <a href="#bnaso">Displaying Error Messages with the <tt>h:message</tt> and <tt>h:messages</tt> Tags</a> describes an example of using the
<tt>style</tt> attribute to specify styles directly in the attribute. A component tag can
instead refer to a CSS class.</p>

<p>The following example shows the use of a <tt>dataTable</tt> tag that references the
style class <tt>list-background</tt>:</p>

<pre>&lt;h:dataTable id="books"
    ...
    styleClass="list-background"
    value="#{bookDBAO.books}"
    var="book"></pre><p>The style sheet that defines this class is <tt>stylesheet.css</tt>, which will be included
in the application. For more information on defining styles, see <i>Cascading Style Sheets Specification</i> at <a href="http://www.w3.org/Style/CSS/">http://www.w3.org/Style/CSS/</a>.</p>



<a name="bnarl"></a><h4>The <tt>value</tt> and <tt>binding</tt> Attributes</h4>
<a name="indexterm-335"></a><a name="indexterm-336"></a><p>A tag representing an output component uses the <tt>value</tt> and <tt>binding</tt> attributes
to bind its component&rsquo;s value or instance, respectively, to an external data source.</p>



<a name="gjdgq"></a><h3>Adding HTML Head and Body Tags</h3>
<a name="indexterm-337"></a><a name="indexterm-338"></a><p>The HTML head (<tt>h:head</tt>) and body (<tt>h:body</tt>) tags add HTML page structure to
JavaServer Faces web pages.</p>


<ul><li><p>The <tt>h:head</tt> tag represents the head element of an HTML page</p>

</li>
<li><p>The <tt>h:body</tt> tag represents the body element of an HTML page</p>

</li></ul>
<p>The following is an example of an XHTML page using the usual
head and body markup tags:</p>

<pre>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  &lt;html xmlns="http://www.w3.org/1999/xhtml">
  &lt;head>
    &lt;title>Add a title&lt;/title>
  &lt;/head>
  &lt;body>
    Add Content
  &lt;/body></pre><p>The following is an example of an XHTML page using <tt>h:head</tt> and
<tt>h:body</tt> tags:</p>

<pre>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  &lt;html xmlns="http://www.w3.org/1999/xhtml"
        xmlns:h="http://java.sun.com/jsf/html">
  &lt;h:head>
    Add a title 
  &lt;/h:head>
  &lt;h:body>
    Add Content
  &lt;/h:body></pre><p>Both of the preceding example code segments render the same HTML elements. The
head and body tags are useful mainly for resource relocation. For more information
on resource relocation, see <a href="#gjgep">Resource Relocation Using <tt>h:output</tt> Tags</a>.</p>



<a name="bnarm"></a><h3>Adding a Form Component</h3>
<a name="indexterm-339"></a><p>An <tt>h:form</tt> tag represents an input form, which includes child components that can
contain data that is either presented to the user or submitted with the
form.</p>

<p><a href="#bnarn">Figure&nbsp;7-1</a> shows a typical login form in which a user enters a user
name and password, then submits the form by clicking the Login button.</p>

<a name="bnarn"></a><p class="caption">Figure&nbsp;7-1 A Typical Form</p><img src="figures/jsfpage-formcomponent.gif" alt="Screen capture of form with User Name and Password text fields and a Login button."></img><p>The <tt>h:form</tt> tag represents the form on the page and encloses all the
components that display or collect data from the user, as shown here:</p>

<pre>&lt;h:form>
... other JavaServer Faces tags and other content...
&lt;/h:form></pre><p><a name="indexterm-340"></a>The <tt>h:form</tt> tag can also include HTML markup to lay out the components
on the page. Note that the <tt>h:form</tt> tag itself does not perform any
layout; its purpose is to collect data and to declare attributes that can
be used by other components in the form.</p>

<p>A page can include multiple <tt>h:form</tt> tags, but only the values from the
form submitted by the user will be included in the postback request.</p>



<a name="bnaro"></a><h3>Using Text Components</h3>
<p>Text components allow users to view and edit text in web applications. The
basic types of text components are as follows:</p>


<ul><li><p>Label, which displays read-only text</p>

</li>
<li><p>Text field, which allows users to enter text, often to be submitted as part of a form</p>

</li>
<li><p>Text area, which is a type of text field that allows users to enter multiple lines of text</p>

</li>
<li><p>Password field, which is a type of text field that displays a set of characters, such as asterisks, instead of the password text that the user enters</p>

</li></ul>
<p><a href="#bnarp">Figure&nbsp;7-2</a> shows examples of these text components.</p>

<a name="bnarp"></a><p class="caption">Figure&nbsp;7-2 Example Text Components</p><img src="figures/jsfpage-textcomponents.gif" alt="Screen capture of form. "User Name" labels a text field. "Password" labels a password field. "Comments" labels a text area."></img><p>Text components can be categorized as either input or output. A JavaServer Faces
output component is rendered as read-only text. An example is a label. A
JavaServer Faces input component is rendered as editable text. An example is a
text field.</p>

<p>The input and output components can each be rendered in various ways to
display more specialized text. </p>

<p><a href="#bnarq">Table&nbsp;7-3</a> lists the tags that represent the input components.</p>

<a name="bnarq"></a><p class="caption">Table&nbsp;7-3 Input Tags</p><table><col width="24%"><col width="75%"><tr><th align="left" valign="top" scope="column"><p>Tag</p>

</th>
<th align="left" valign="top" scope="column"><p>Function</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-341"></a><tt>h:inputHidden</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Allows a page author to
include a hidden variable in a page</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-342"></a><tt>h:inputSecret</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>The standard password field: accepts one
line of text with no spaces and displays it as a set of
asterisks as it is typed</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-343"></a><tt>h:inputText</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>The standard text field: accepts a one-line text
string</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-344"></a><tt>h:inputTextarea</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>The standard text area: accepts multiple lines of text</p>

</td>
</tr>
</table><p>The input tags support the tag attributes shown in <a href="#gkcnh">Table&nbsp;7-4</a> in addition
to those described in <a href="#bnarg">Common Component Tag Attributes</a>. Note that this table does not include all
the attributes supported by the input tags but just those that are used
most often. For the complete list of attributes, refer to the documentation at
<a href="http://download.oracle.com/javaee/6/javaserverfaces/2.1/docs/vdldocs/facelets/">http://download.oracle.com/javaee/6/javaserverfaces/2.1/docs/vdldocs/facelets/</a>. </p>

<a name="gkcnh"></a><p class="caption">Table&nbsp;7-4 Input Tag Attributes</p><table><col width="33%"><col width="66%"><tr><th align="left" valign="top" scope="column"><p>Attribute</p>

</th>
<th align="left" valign="top" scope="column"><p>Description</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-345"></a><a name="indexterm-346"></a><tt>converter</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Identifies a converter that will be used to convert the component&rsquo;s local
data. See <a href="bnast.html">Using the Standard Converters</a> for more information on how to use this attribute.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>converterMessage</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Specifies an
error message to display when the converter registered on the component fails.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>dir</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Specifies the
direction of the text displayed by this component. Acceptable values are <tt>LTR</tt>, meaning
left-to-right, and <tt>RTL</tt>, meaning right-to-left.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>label</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Specifies a name that can be used to identify
this component in error messages.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>lang</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Specifies the code for the language used in the
rendered markup, such as <tt>en_US</tt>.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>required</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Takes a <tt>boolean</tt> value that indicates whether the user must
enter a value in this component.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>requiredMessage</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Specifies an error message to display when
the user does not enter a value into the component.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-347"></a><a name="indexterm-348"></a><tt>validator</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Identifies a method expression
pointing to a managed bean method that performs validation on the component&rsquo;s data.
See <a href="bnatn.html#bnatr">Referencing a Method That Performs Validation</a> for an example of using the <tt>f:validator</tt> tag.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>f:validatorMessage</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Specifies an error
message to display when the validator registered on the component fails to validate
the component&rsquo;s local value.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-349"></a><a name="indexterm-350"></a><a name="indexterm-351"></a><tt>valueChangeListener</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Identifies a method expression that points to a managed
bean method that handles the event of entering a value in this component.
See <a href="bnatn.html#bnats">Referencing a Method That Handles a Value-Change Event</a> for an example of using <tt>valueChangeListener</tt>.</p>

</td>
</tr>
</table><p><a href="#gjfwe">Table&nbsp;7-5</a> lists the tags that represent the output components.</p>

<a name="gjfwe"></a><p class="caption">Table&nbsp;7-5 Output Tags</p><table><col width="23%"><col width="76%"><tr><th align="left" valign="top" scope="column"><p>Tag</p>

</th>
<th align="left" valign="top" scope="column"><p>Function</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-352"></a><tt>h:outputFormat</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays a localized message</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-353"></a><tt>h:outputLabel</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>The standard
read-only label: displays a component as a label for a specified input field</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-354"></a><tt>h:outputLink</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays
an <tt>&lt;a href></tt> tag that links to another page without generating an action event</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><a name="indexterm-355"></a><tt>h:outputText</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays
a one-line text string</p>

</td>
</tr>
</table><p>The output tags support the <tt>converter</tt> tag attribute in addition to those listed
in <a href="#bnarg">Common Component Tag Attributes</a>.</p>

<p>The rest of this section explains how to use some of the
tags listed in <a href="#bnarq">Table&nbsp;7-3</a> and <a href="#gjfwe">Table&nbsp;7-5</a>. The other tags are written in a
similar way.</p>



<a name="bnarr"></a><h4>Rendering a Text Field with the <tt>h:inputText</tt> Tag</h4>
<a name="indexterm-356"></a><a name="indexterm-357"></a><p>The <tt>h:inputText</tt> tag is used to display a text field. A similar tag,
the <tt>h:outputText</tt> tag, displays a read-only, single-line string. This section shows you how
to use the <tt>h:inputText</tt> tag. The <tt>h:outputText</tt> tag is written in a similar
way.</p>

<p>Here is an example of an <tt>h:inputText</tt> tag:</p>

<pre>&lt;h:inputText id="name" label="Customer Name" size="50"
    value="#{cashier.name}"
    required="true"
    requiredMessage="#{customMessages.CustomerName}">
    &lt;f:valueChangeListener
        type="com.sun.bookstore6.listeners.NameChanged" />
 &lt;/h:inputText></pre><p>The <tt>label</tt> attribute specifies a user-friendly name that will be used in the
substitution parameters of error messages displayed for this component.</p>

<p>The <tt>value</tt> attribute refers to the <tt>name</tt> property of a managed bean named
<tt>CashierBean</tt>. This property holds the data for the <tt>name</tt> component. After the user
submits the form, the value of the <tt>name</tt> property in <tt>CashierBean</tt> will be
set to the text entered in the field corresponding to this tag.</p>

<p>The <tt>required</tt> attribute causes the page to reload, displaying errors, if the user
does not enter a value in the <tt>name</tt> text field. The JavaServer Faces
implementation checks whether the value of the component is null or is an
empty string.</p>

<p>If your component must have a non-null value or a <tt>String</tt> value at
least one character in length, you should add a <tt>required</tt> attribute to your
tag and set its value to <tt>true</tt>. If your tag has a <tt>required</tt>
attribute that is set to <tt>true</tt> and the value is null or a
zero-length string, no other validators that are registered on the tag are called.
If your tag does not have a <tt>required</tt> attribute set to <tt>true</tt>, other
validators that are registered on the tag are called, but those validators must
handle the possibility of a null or zero-length string. See <a href="gircz.html#gkcrg">Validating Null and Empty Strings</a> for more
information.</p>



<a name="bnarv"></a><h4>Rendering a Password Field with the <tt>h:inputSecret</tt> Tag</h4>
<p><a name="indexterm-358"></a>The <tt>h:inputSecret</tt> tag renders an <tt>&lt;input type="password"></tt> HTML tag. When the user types a string
into this field, a row of asterisks is displayed instead of the text
typed by the user. Here is an example:</p>

<pre>&lt;h:inputSecret redisplay="false"
    value="#{LoginBean.password}" /></pre><p><a name="indexterm-359"></a>In this example, the <tt>redisplay</tt> attribute is set to <tt>false</tt>. This will
prevent the password from being displayed in a query string or in the
source file of the resulting HTML page.</p>



<a name="bnars"></a><h4>Rendering a Label with the <tt>h:outputLabel</tt> Tag</h4>
<a name="indexterm-360"></a><p>The <tt>h:outputLabel</tt> tag is used to attach a label to a specified input
field for the purpose of making it accessible. The following page uses an
<tt>h:outputLabel</tt> tag to render the label of a check box:</p>

<pre>&lt;h:selectBooleanCheckbox
     id="fanClub"
     binding="#{cashier.specialOffer}" />
&lt;h:outputLabel for="fanClub"
     binding="#{cashier.specialOfferText}" >
   &lt;h:outputText id="fanClubLabel"
        value="#{bundle.DukeFanClub}" />
&lt;/h:outputLabel>
...</pre><p><a name="indexterm-361"></a>The <tt>for</tt> attribute of the <tt>h:outputLabel</tt> tag maps to the <tt>id</tt> of the input
field to which the label is attached. The <tt>h:outputText</tt> tag nested inside the
<tt>h:outputLabel</tt> tag represents the label component. The <tt>value</tt> attribute on the <tt>h:outputText</tt> tag indicates
the text that is displayed next to the input field.</p>

<p>Instead of using an <tt>h:outputText</tt> tag for the text displayed as a label,
you can simply use the <tt>h:outputLabel</tt> tag&rsquo;s <tt>value</tt> attribute. The following code
snippet shows what the previous code snippet would look like if it used
the <tt>value</tt> attribute of the <tt>h:outputLabel</tt> tag to specify the text of the
label:</p>

<pre>&lt;h:selectBooleanCheckbox
     id="fanClub"
     binding="#{cashier.specialOffer}" />
&lt;h:outputLabel for="fanClub"
     binding="#{cashier.specialOfferText}"
     value="#{bundle.DukeFanClub}" />
&lt;/h:outputLabel>
...</pre>

<a name="bnart"></a><h4>Rendering a Hyperlink with the <tt>h:outputLink</tt> Tag</h4>
<a name="indexterm-362"></a><p>The <tt>h:outputLink</tt> tag is used to render a hyperlink that, when clicked, loads
another page but does not generate an action event. You should use this
tag instead of the <tt>h:commandLink</tt> tag if you always want the URL specified
by the <tt>h:outputLink</tt> tag&rsquo;s <tt>value</tt> attribute to open and do not want
any processing to be performed when the user clicks the link. Here is
an example:</p>

<pre>&lt;h:outputLink value="javadocs">
    Documentation for this demo
&lt;/h:outputLink></pre><p>The text in the body of the <tt>outputLink</tt> tag identifies the text that
the user clicks to get to the next page.</p>



<a name="bnaru"></a><h4>Displaying a Formatted Message with the <tt>h:outputFormat</tt> Tag</h4>
<p><a name="indexterm-363"></a><a name="indexterm-364"></a><a name="indexterm-365"></a>The <tt>h:outputFormat</tt> tag allows display of concatenated messages as a <tt>MessageFormat</tt> pattern, as described
in the API documentation for <tt>java.text.MessageFormat</tt>. Here is an example of an <tt>outputFormat</tt>
tag:</p>

<pre>&lt;h:outputFormat value="Hello, {0}!">
    &lt;f:param value="#{hello.name}"/>
&lt;/h:outputFormat></pre><p><a name="indexterm-366"></a><a name="indexterm-367"></a><a name="indexterm-368"></a>The <tt>value</tt> attribute specifies the <tt>MessageFormat</tt> pattern. The <tt>param</tt> tag specifies the substitution parameters
for the message. The value of the parameter replaces the <tt>{0}</tt> in the
sentence. If the value of <tt>"#{hello.name}"</tt> is &ldquo;Bill&rdquo;, the message displayed in
the page is as follows:</p>

<pre>Hello, Bill!</pre><p>An <tt>h:outputFormat</tt> tag can include more than one <tt>param</tt> tag for those
messages that have more than one parameter that must be concatenated into the
message. If you have more than one parameter for one message, make sure
that you put the <tt>param</tt> tags in the proper order so that the
data is inserted in the correct place in the message. Here is the
preceding example modified with an additional parameter:</p>

<pre>&lt;h:outputFormat value="Hello, {0}! You are visitor number {1} to the page.">
&lt;f:param value="#{hello.name}" />
&lt;f:param value="#{bean.numVisitor}"/>
&lt;/h:outputFormat></pre><p>The value of <tt>{1}</tt> is replaced by the second parameter. The parameter is
an EL expression, <tt>bean.numVisitor</tt>, where the property <tt>numVisitor</tt> of the managed bean <tt>bean</tt>
keeps track of visitors to the page. This is an example of a
value-expression-enabled tag attribute accepting an EL expression. The message displayed in the page is
now as follows:</p>

<pre>Hello, Bill! You are visitor number 10 to the page.</pre>

<a name="bnarw"></a><h3>Using Command Component Tags for Performing Actions and Navigation</h3>
<p>In JavaServer Faces applications, the button and hyperlink component tags are used to
perform actions, such as submitting a form, and for navigating to another page.
These tags are called command component tags because they perform an action when
activated.</p>

<p>The <tt>h:commandButton</tt> tag is rendered as a button. The <tt>h:commandLink</tt> tag is rendered
as a hyperlink.</p>

<p>In addition to the tag attributes listed in <a href="#bnarg">Common Component Tag Attributes</a>, the <tt>h:commandButton</tt> and
<tt>h:commandLink</tt> tags can use the following attributes:</p>


<ul><li><p><a name="indexterm-369"></a><a name="indexterm-370"></a><tt>action</tt>, which is either a logical outcome <tt>String</tt> or a method expression pointing to a bean method that returns a logical outcome <tt>String</tt>. In either case, the logical outcome <tt>String</tt> is used to determine what page to access when the command component tag is activated.</p>

</li>
<li><p><a name="indexterm-371"></a><a name="indexterm-372"></a><tt>actionListener</tt>, which is a method expression pointing to a bean method that processes an action event fired by the command component tag.</p>

</li></ul>
<p>See <a href="bnatn.html#bnatp">Referencing a Method That Performs Navigation</a> for more information on using the <tt>action</tt> attribute. See <a href="bnatn.html#bnatq">Referencing a Method That Handles an Action Event</a> for details
on using the <tt>actionListener</tt> attribute.</p>



<a name="bnarx"></a><h4>Rendering a Button with the <tt>h:commandButton</tt> Tag</h4>
<a name="indexterm-373"></a><p>If you are using a <tt>commandButton</tt> component tag, the data from the current
page is processed when a user clicks the button, and the next page
is opened. Here is an example of the <tt>h:commandButton</tt> tag:</p>

<pre>&lt;h:commandButton value="Submit"
     action="#{cashier.submit}"/></pre><p>Clicking the button will cause the <tt>submit</tt> method of <tt>CashierBean</tt> to be invoked
because the <tt>action</tt> attribute references this method. The <tt>submit</tt> method performs some processing and
returns a logical outcome.</p>

<p>The <tt>value</tt> attribute of the example <tt>commandButton</tt> tag references the button&rsquo;s label.
For information on how to use the <tt>action</tt> attribute, see <a href="bnatn.html#bnatp">Referencing a Method That Performs Navigation</a>.</p>



<a name="gkbuj"></a><h4>Rendering a Hyperlink with the <tt>h:commandLink</tt> Tag</h4>
<a name="indexterm-374"></a><a name="indexterm-375"></a><p>The <tt>h:commandLink</tt> tag represents an HTML hyperlink and is rendered as an HTML
<tt>&lt;a></tt> element. This tag acts like a form&rsquo;s Submit button and is used
to submit an action event to the application.</p>

<p><a name="indexterm-376"></a>A <tt>h:commandLink</tt> tag must include a nested <tt>h:outputText</tt> tag, which represents the text
that the user clicks to generate the event. Here is an example:</p>

<pre>&lt;h:commandLink id="NAmerica" action="bookstore"
     actionListener="#{localeBean.chooseLocaleFromLink}">
     &lt;h:outputText value="#{bundle.English}" />
&lt;/h:commandLink></pre><p>This tag will render the following HTML:</p>

<pre>&lt;a id="_id3:NAmerica" href="#"
     onclick="document.forms['_id3']['_id3:NAmerica'].
     value='_id3:NAmerica';
     document.forms['_id3'].submit();
     return false;">English&lt;/a></pre>
<hr><p><b>Note - </b>The <tt>h:commandLink</tt> tag will render JavaScript scripting language. If you use this
tag, make sure that your browser is enabled for JavaScript technology.</p>


<hr>


<a name="bnasb"></a><h3>Adding Graphics and Images with the <tt>h:graphicImage</tt> Tag</h3>
<a name="indexterm-377"></a><p>In a JavaServer Faces application, use the <tt>h:graphicImage</tt> tag to render an image
on a page:</p>

<pre>&lt;h:graphicImage id="mapImage" url="/template/world.jpg"/></pre><p>The <tt>url</tt> attribute specifies the path to the image. The URL of the
example tag begins with a <tt>/</tt>, which adds the relative context path of
the web application to the beginning of the path to the image.</p>

<p>Alternatively, you can use the facility described in <a href="girgm.html">Resources</a> to point to
the image location. Here is an example:</p>

<pre>&lt;h:graphicImage value="#{resource['images:wave.med.gif']}"/></pre>

<a name="bnasc"></a><h3>Laying Out Components with the <tt>h:panelGrid</tt> and <tt>h:panelGroup</tt> Tags</h3>
<a name="indexterm-378"></a><a name="indexterm-379"></a><p>In a JavaServer Faces application, you use a panel as a layout
container for a set of other components. A panel is rendered as an
HTML table. <a href="#bnasd">Table&nbsp;7-6</a> lists the tags used to create panels.</p>

<a name="bnasd"></a><p class="caption">Table&nbsp;7-6 Panel Component Tags</p><table><col width="17%"><col width="46%"><col width="36%"><tr><th align="left" valign="top" scope="column"><p>Tag</p>

</th>
<th align="left" valign="top" scope="column"><p> Attributes</p>

</th>
<th align="left" valign="top" scope="column"><p>Function</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>h:panelGrid</tt></p>

</td>
<td align="left" valign="top" scope="row"><p><tt>columns,columnClasses</tt>, <tt>footerClass</tt>, <tt>headerClass</tt>,
<tt>panelClass</tt>, <tt>rowClasses</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Displays a table</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>h:panelGroup</tt></p>

</td>
<td align="left" valign="top" scope="row"><p><tt>layout</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Groups a set of components under one parent</p>

</td>
</tr>
</table><p>The <tt>h:panelGrid</tt> tag is used to represent an entire table. The <tt>h:panelGroup</tt> tag
is used to represent rows in a table. Other tags are used to
represent individual cells in the rows.</p>

<p>The <tt>columns</tt> attribute defines how to group the data in the table and
therefore is required if you want your table to have more than one
column. The <tt>h:panelGrid</tt> tag also has a set of optional attributes that specify
CSS classes: <tt>columnClasses</tt>, <tt>footerClass</tt>, <tt>headerClass</tt>, <tt>panelClass</tt>, and <tt>rowClasses</tt>. </p>

<p>If the <tt>headerClass</tt> attribute value is specified, the <tt>panelGrid</tt> must have a header
as its first child. Similarly, if a <tt>footerClass</tt> attribute value is specified, the
<tt>panelGrid</tt> must have a footer as its last child.</p>

<p>Here is an example:</p>

<pre>&lt;h:panelGrid columns="3" headerClass="list-header"
    rowClasses="list-row-even, list-row-odd"
    styleClass="list-background"
    title="#{bundle.Checkout}">
    &lt;f:facet name="header">
        &lt;h:outputText value="#{bundle.Checkout}"/>
    &lt;/f:facet>
    &lt;h:outputText value="#{bundle.Name}" />
    &lt;h:inputText id="name" size="50"
         value="#{cashier.name}"
        required="true">
         &lt;f:valueChangeListener
             type="listeners.NameChanged" />
    &lt;/h:inputText>
    &lt;h:message styleClass="validationMessage" for="name"/>
    &lt;h:outputText value="#{bundle.CCNumber}"/>
    &lt;h:inputText id="ccno" size="19"
        converter="CreditCardConverter" required="true">
         &lt;bookstore:formatValidator
             formatPatterns="9999999999999999|
                9999 9999 9999 9999|9999-9999-9999-9999"/>
    &lt;/h:inputText>
    &lt;h:message styleClass="validationMessage"  for="ccno"/>
    ...
&lt;/h:panelGrid></pre><p>The preceding <tt>h:panelGrid</tt> tag is rendered as a table that contains components in
which a customer inputs personal information. This <tt>h:panelGrid</tt> tag uses style sheet classes
to format the table. The following code shows the <tt>list-header</tt> definition:</p>

<pre>.list-header {
    background-color: #ffffff;
    color: #000000;
    text-align: center;
}</pre><p><a name="indexterm-380"></a>Because the <tt>h:panelGrid</tt> tag specifies a <tt>headerClass</tt>, the <tt>panelGrid</tt> must contain a header. The
example <tt>panelGrid</tt> tag uses a <tt>facet</tt> tag for the header. Facets can
have only one child, so an <tt>h:panelGroup</tt> tag is needed if you
want to group more than one component within a <tt>facet</tt>. The example <tt>h:panelGrid</tt>
tag has only one cell of data, so an <tt>h:panelGroup</tt> tag is not needed.</p>

<p>The <tt>h:panelGroup</tt> tag has an attribute, <tt>layout</tt>, in addition to those listed in
<a href="#bnarg">Common Component Tag Attributes</a>. If the <tt>layout</tt> attribute has the value <tt>block</tt>, an HTML <tt>div</tt>
element is rendered to enclose the row; otherwise, an HTML <tt>span</tt> element is
rendered to enclose the row. If you are specifying styles for the <tt>h:panelGroup</tt>
tag, you should set the <tt>layout</tt> attribute to <tt>block</tt> in order for the styles
to be applied to the components within the <tt>h:panelGroup</tt> tag. You should
do this because styles, such as those that set width and height, are
not applied to inline elements, which is how content enclosed by the <tt>span</tt>
element is defined.</p>

<p>An <tt>h:panelGroup</tt> tag can also be used to encapsulate a nested tree of
components so that the tree of components appears as a single component to
the parent component.</p>

<p><a name="indexterm-381"></a>Data, represented by the nested tags, is grouped into rows according to the
value of the <tt>columns</tt> attribute of the <tt>h:panelGrid</tt> tag. The <tt>columns</tt> attribute in the
example is set to <tt>3</tt>, and therefore the table will have three columns.
The column in which each component is displayed is determined by the order
in which the component is listed on the page modulo 3. So,
if a component is the fifth one in the list of components, that
component will be in the 5 modulo 3 column, or column 2.</p>



<a name="bnase"></a><h3>Displaying Components for Selecting One Value</h3>
<p>Another commonly used component is one that allows a user to select one
value, whether it is the only value available or one of a
set of choices. The most common tags for this kind of component are
as follows:</p>


<ul><li><p>An <tt>h:selectBooleanCheckbox</tt> tag, displayed as a check box, which represents a Boolean state</p>

</li>
<li><p>An <tt>h:selectOneRadio</tt> tag, displayed as a set of radio buttons</p>

</li>
<li><p>An <tt>h:selectOneMenu</tt> tag, displayed as a drop-down menu, with a scrollable list</p>

</li>
<li><p>An <tt>h:selectOneListbox</tt> tag, displayed as a list box, with an unscrollable list</p>

</li></ul>
<p><a href="#bnasf">Figure&nbsp;7-3</a> shows examples of these components.</p>

<a name="bnasf"></a><p class="caption">Figure&nbsp;7-3 Example Components for Selecting One Item</p><img src="figures/jsfpage-selectone.gif" alt="Screen capture of radio buttons, check box, drop-down menu, and list box."></img>

<a name="bnasg"></a><h4>Displaying a Check Box Using the <tt>h:selectBooleanCheckbox</tt> Tag</h4>
<p><a name="indexterm-382"></a>The <tt>h:selectBooleanCheckbox</tt> tag is the only tag that JavaServer Faces technology provides for
representing a Boolean state.</p>

<p>Here is an example that shows how to use the <tt>h:selectBooleanCheckbox</tt> tag:</p>

<pre>&lt;h:selectBooleanCheckbox
    id="fanClub"
    rendered="false"
    binding="#{cashier.specialOffer}" />
&lt;h:outputLabel
    for="fanClub"
    rendered="false"
    binding="#{cashier.specialOfferText}">
     &lt;h:outputText
        id="fanClubLabel"
        value="#{bundle.DukeFanClub}" />
&lt;/h:outputLabel></pre><p>This example tag displays a check box to allow users to indicate
whether they want to join the Duke Fan Club. The label for the
check box is rendered by the <tt>outputLabel</tt> tag. The text is represented by
the nested <tt>outputText</tt> tag.</p>



<a name="bnash"></a><h4>Displaying a Menu Using the <tt>h:selectOneMenu</tt> Tag</h4>
<a name="indexterm-383"></a><p><a name="indexterm-384"></a><a name="indexterm-385"></a>A component that allows the user to select one value from a set
of values can be rendered as a list box, a set of radio
buttons, or a menu. This section describes the <tt>h:selectOneMenu</tt> tag. The <tt>h:selectOneRadio</tt> and
<tt>h:selectOneListbox</tt> tags are used in a similar way. The <tt>h:selectOneListbox</tt> tag is similar
to the <tt>h:selectOneMenu</tt> tag except that <tt>h:selectOneListbox</tt> defines a <tt>size</tt> attribute that
determines how many of the items are displayed at once.</p>

<p>The <tt>h:selectOneMenu</tt> tag represents a component that contains a list of items from
which a user can choose one item. This menu component is also commonly
known as a drop-down list or a combo box. The following code snippet
shows how the <tt>h:selectOneMenu</tt> tag is used to allow the user to select
a shipping method:</p>

<pre>&lt;h:selectOneMenu id="shippingOption"
    required="true"
    value="#{cashier.shippingOption}">
    &lt;f:selectItem
        itemValue="2"
        itemLabel="#{bundle.QuickShip}"/>
    &lt;f:selectItem
        itemValue="5"
        itemLabel="#{bundle.NormalShip}"/>
    &lt;f:selectItem
        itemValue="7"
        itemLabel="#{bundle.SaverShip}"/>
 &lt;/h:selectOneMenu></pre><p>The <tt>value</tt> attribute of the <tt>h:selectOneMenu</tt> tag maps to the property that holds
the currently selected item&rsquo;s value. You are not required to provide a value
for the currently selected item. If you don&rsquo;t provide a value, the first
item in the list is selected by default.</p>

<p><a name="indexterm-386"></a><a name="indexterm-387"></a>Like the <tt>h:selectOneRadio</tt> tag, the <tt>selectOneMenu</tt> tag must contain either an <tt>f:selectItems</tt>
tag or a set of <tt>f:selectItem</tt> tags for representing the items in the list.
<a href="#bnask">Using the <tt>f:selectItem</tt> and <tt>f:selectItems</tt> Tags</a> describes these tags.</p>



<a name="bnasi"></a><h3>Displaying Components for Selecting Multiple Values</h3>
<a name="indexterm-388"></a><p>In some cases, you need to allow your users to select multiple
values rather than just one value from a list of choices. You can
do this using one of the following component tags:</p>


<ul><li><p>An <tt>h:selectManyCheckbox</tt> tag, displayed as a set of check boxes</p>

</li>
<li><p><a name="indexterm-389"></a>An <tt>h:selectManyMenu</tt> tag, displayed as a drop-down menu</p>

</li>
<li><p><a name="indexterm-390"></a>An <tt>h:selectManyListbox</tt> tag, displayed as a list box</p>

</li></ul>
<p><a href="#bnasj">Figure&nbsp;7-4</a> shows examples of these components.</p>

<a name="bnasj"></a><p class="caption">Figure&nbsp;7-4 Example Components for Selecting Multiple Values</p><img src="figures/jsfpage-selectmany.gif" alt="Screen capture of check box set, drop-down menu, and list box."></img><p>These tags allow the user to select zero or more values from
a set of values. This section explains the <tt>h:selectManyCheckbox</tt> tag. The <tt>h:selectManyListbox</tt> and <tt>h:selectManyMenu</tt>
tags are used in a similar way.</p>

<p>Unlike a menu, a list box displays a subset of items in
a box; a menu displays only one item at a time when the
user is not selecting the menu. The <tt>size</tt> attribute of the <tt>h:selectManyListbox</tt> tag determines
the number of items displayed at one time. The list box includes a
scroll bar for scrolling through any remaining items in the list.</p>

<p>The <tt>h:selectManyCheckbox</tt> tag renders a set of check boxes, with each check box
representing one value that can be selected:</p>

<pre>&lt;h:selectManyCheckbox
    id="newsletters"
    layout="pageDirection"
    value="#{cashier.newsletters}">
    &lt;f:selectItems
        value="#{newsletters}"/>
&lt;/h:selectManyCheckbox></pre><p>The <tt>value</tt> attribute of the <tt>h:selectManyCheckbox</tt> tag identifies the <tt>newsletters</tt> property of
the <tt>Cashier</tt> managed bean. This property holds the values of the currently selected
items from the set of check boxes. You are not required to
provide a value for the currently selected items. If you don&rsquo;t provide a
value, the first item in the list is selected by default.</p>

<p>The <tt>layout</tt> attribute indicates how the set of check boxes is arranged on
the page. Because layout is set to <tt>pageDirection</tt>, the check boxes are arranged
vertically. The default is <tt>lineDirection</tt>, which aligns the check boxes horizontally.</p>

<p><a name="indexterm-391"></a><a name="indexterm-392"></a>The <tt>h:selectManyCheckbox</tt> tag must also contain a tag or set of tags representing
the set of check boxes. To represent a set of items, you use
the <tt>f:selectItems</tt> tag. To represent each item individually, you use a <tt>f:selectItem</tt> tag.
The following subsection explains these tags in more detail.</p>



<a name="bnask"></a><h3>Using the <tt>f:selectItem</tt> and <tt>f:selectItems</tt> Tags</h3>
<a name="indexterm-393"></a><a name="indexterm-394"></a><p>The <tt>f:selectItem</tt> and <tt>f:selectItems</tt> tags represent components that can be nested inside a
component that allows you to select one or multiple items. An <tt>f:selectItem</tt> tag
contains the value, label, and description of a single item. An <tt>f:selectItems</tt> tag contains
the values, labels, and descriptions of the entire list of items.</p>

<p>You can use either a set of <tt>f:selectItem</tt> tags or a single <tt>f:selectItems</tt>
tag within your component tag.</p>

<p>The advantages of using the <tt>f:selectItems</tt> tag are as follows.</p>


<ul><li><p>Items can be represented by using different data structures, including <tt>Array</tt>, <tt>Map</tt>, and <tt>Collection</tt>. The value of the <tt>f:selectItems</tt> tag can represent even a generic collection of POJOs.</p>

</li>
<li><p>Different lists can be concatenated into a single component, and the lists can be grouped within the component.</p>

</li>
<li><p>Values can be generated dynamically at runtime.</p>

</li></ul>
<p>The advantages of using <tt>f:selectItem</tt> are as follows:</p>


<ul><li><p>Items in the list can be defined from the page.</p>

</li>
<li><p>Less code is needed in the bean for the <tt>selectItem</tt> properties.</p>

</li></ul>
<p>The rest of this section shows you how to use the <tt>f:selectItems</tt>
and <tt>f:selectItem</tt> tags.</p>



<a name="bnasm"></a><h4>Using the <tt>f:selectItems</tt> Tag</h4>
<a name="indexterm-395"></a><p>The following example from <a href="#bnasi">Displaying Components for Selecting Multiple Values</a> shows how to use the <tt>h:selectManyCheckbox</tt> tag:</p>

<pre>&lt;h:selectManyCheckbox
    id="newsletters"
    layout="pageDirection"
    value="#{cashier.newsletters}">
    &lt;f:selectItems
        value="#{newsletters}"/>
&lt;/h:selectManyCheckbox></pre><p>The <tt>value</tt> attribute of the <tt>f:selectItems</tt> tag is bound to the managed bean
<tt>newsletters</tt>.</p>

<p>You can also create the list of items programmatically in the managed bean.
See <a href="bnaty.html">Writing Bean Properties</a> for information on how to write a managed bean property for
one of these tags.</p>



<a name="bnasn"></a><h4>Using the <tt>f:selectItem</tt> Tag</h4>
<a name="indexterm-396"></a><p>The <tt>f:selectItem</tt> tag represents a single item in a list of items. Here
is the example from <a href="#bnash">Displaying a Menu Using the <tt>h:selectOneMenu</tt> Tag</a> once again:</p>

<pre>&lt;h:selectOneMenu
      id="shippingOption" required="true"
      value="#{cashier.shippingOption}">
    &lt;f:selectItem
        itemValue="2"
        itemLabel="#{bundle.QuickShip}"/>
    &lt;f:selectItem
        itemValue="5"
        itemLabel="#{bundle.NormalShip}"/>
    &lt;f:selectItem
        itemValue="7"
        itemLabel="#{bundle.SaverShip}"/>
 &lt;/h:selectOneMenu></pre><p>The <tt>itemValue</tt> attribute represents the default value for the <tt>selectItem</tt> tag. The <tt>itemLabel</tt>
attribute represents the <tt>String</tt> that appears in the drop-down menu component on the page.</p>

<p>The <tt>itemValue</tt> and <tt>itemLabel</tt> attributes are value-binding-enabled, meaning that they can use value-binding
expressions to refer to values in external objects. These attributes can also define
literal values, as shown in the example <tt>h:selectOneMenu</tt> tag.</p>



<a name="bnarz"></a><h3>Using Data-Bound Table Components</h3>
<a name="indexterm-397"></a><p>Data-bound table components display relational data in a tabular format. In a JavaServer
Faces application, the <tt>h:dataTable</tt> component tag supports binding to a collection of data
objects and displays the data as an HTML table. The <tt>h:column</tt> tag represents
a column of data within the table, iterating over each record in the
data source, which is displayed as a row. Here is an example:</p>

<pre>&lt;h:dataTable id="items"
    captionClass="list-caption"
    columnClasses="list-column-center, list-column-left,
         list-column-right, list-column-center"
    footerClass="list-footer"
    headerClass="list-header"
    rowClasses="list-row-even, list-row-odd"
    styleClass="list-background">
    &lt;h:column headerClass="list-header-left">
        &lt;f:facet name="header">
            &lt;h:outputText value=Quantity"" />
        &lt;/f:facet>
        &lt;h:inputText id="quantity" size="4"
            value="#{item.quantity}" >
            ...
        &lt;/h:inputText>
        ...
    &lt;/h:column>
    &lt;h:column>
        &lt;f:facet name="header">
            &lt;h:outputText value="Title"/>
        &lt;/f:facet>
        &lt;h:commandLink>
            &lt;h:outputText value="#{item.title}"/>
        &lt;/h:commandLink>
    &lt;/h:column>
    ...
    &lt;f:facet name="footer"
        &lt;h:panelGroup>
            &lt;h:outputText value="Total}"/>
            &lt;h:outputText value="#{cart.total}" />
                &lt;f:convertNumber type="currency" />
            &lt;/h:outputText>
        &lt;/h:panelGroup>
    &lt;/f:facet>
&lt;/h:dataTable></pre><p>The example <tt>h:dataTable</tt> tag displays the books in the shopping cart, as well
as the quantity of each book in the shopping cart, the prices, and
a set of buttons the user can click to remove books from
the shopping cart.</p>

<p>The <tt>h:column</tt> tags represent columns of data in a data component. While the
data component is iterating over the rows of data, it processes the column
component associated with each <tt>h:column</tt> tag for each row in the table.</p>

<p>The <tt>h:dataTable</tt> tag shown in the preceding code example iterates through the list
of books (<tt>cart.items</tt>) in the shopping cart and displays their titles, authors, and
prices. Each time the <tt>h:dataTable</tt> tag iterates through the list of books,
it renders one cell in each column.</p>

<p>The <tt>h:dataTable</tt> and <tt>h:column</tt> tags use facets to represent parts of the table
that are not repeated or updated. These parts include headers, footers, and captions.</p>

<p>In the preceding example, <tt>h:column</tt> tags include <tt>f:facet</tt> tags for representing column
headers or footers. The <tt>h:column</tt> tag allows you to control the styles
of these headers and footers by supporting the <tt>headerClass</tt> and <tt>footerClass</tt> attributes. These attributes
accept space-separated lists of CSS classes, which will be applied to the header
and footer cells of the corresponding column in the rendered table.</p>

<p>Facets can have only one child, so an <tt>h:panelGroup</tt> tag is needed if
you want to group more than one component within an <tt>f:facet</tt>. Because
the facet tag representing the footer includes more than one tag, the <tt>panelGroup</tt>
is needed to group those tags. Finally, this <tt>h:dataTable</tt> tag includes an <tt>f:facet</tt>
tag with its <tt>name</tt> attribute set to <tt>caption</tt>, causing a table caption to be
rendered below the table.</p>

<p>This table is a classic use case for a data component because
the number of books might not be known to the application developer or
the page author when that application is developed. The data component can dynamically
adjust the number of rows of the table to accommodate the underlying data.</p>

<p>The <tt>value</tt> attribute of an <tt>h:dataTable</tt> tag references the data to be included
in the table. This data can take the form of any of the
following:</p>


<ul><li><p>A list of beans</p>

</li>
<li><p>An array of beans</p>

</li>
<li><p>A single bean</p>

</li>
<li><p>A <tt>javax.faces.model.DataModel</tt> object</p>

</li>
<li><p>A <tt>java.sql.ResultSet</tt> object</p>

</li>
<li><p>A <tt>javax.servlet.jsp.jstl.sql.Result</tt> object</p>

</li>
<li><p>A <tt>javax.sql.RowSet</tt> object</p>

</li></ul>
<p>All data sources for data components have a <tt>DataModel</tt> wrapper. Unless you explicitly
construct a <tt>DataModel</tt> wrapper, the JavaServer Faces implementation will create one around data
of any of the other acceptable types. See <a href="bnaty.html">Writing Bean Properties</a> for more information on how
to write properties for use with a data component.</p>

<p>The <tt>var</tt> attribute specifies a name that is used by the components within
the <tt>h:dataTable</tt> tag as an alias to the data referenced in the <tt>value</tt>
attribute of <tt>dataTable</tt>.</p>

<p>In the example <tt>h:dataTable</tt> tag, the <tt>value</tt> attribute points to a list of
books. The <tt>var</tt> attribute points to a single book in that list. As
the <tt>h:dataTable</tt> tag iterates through the list, each reference to <tt>item</tt> points to
the current book in the list.</p>

<p>The <tt>h:dataTable</tt> tag also has the ability to display only a subset of
the underlying data. This feature is not shown in the preceding example. To
display a subset of the data, you use the optional <tt>first</tt> and
<tt>rows</tt> attributes.</p>

<p>The <tt>first</tt> attribute specifies the first row to be displayed. The <tt>rows</tt> attribute
specifies the number of rows, starting with the first row, to be displayed.
For example, if you wanted to display records 2 through 10 of the
underlying data, you would set <tt>first</tt> to 2 and <tt>rows</tt> to 9.
When you display a subset of the data in your pages, you might
want to consider including a link or button that causes subsequent rows to
display when clicked. By default, both <tt>first</tt> and <tt>rows</tt> are set to
zero, and this causes all the rows of the underlying data to display.</p>

<p><a href="#gkbuk">Table&nbsp;7-7</a> shows the optional attributes for the <tt>h:dataTable</tt> tag.</p>

<a name="gkbuk"></a><p class="caption">Table&nbsp;7-7 Optional Attributes for the <tt>h:dataTable</tt> Tag</p><table><col width="50%"><col width="50%"><tr><th align="left" valign="top" scope="column"><p>Attribute</p>

</th>
<th align="left" valign="top" scope="column"><p>Defines Styles for</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>captionClass</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Table caption</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>columnClasses</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>All the
columns</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>footerClass</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Footer</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>headerClass</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Header</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>rowClasses</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Rows</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>styleClass</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>The entire table</p>

</td>
</tr>
</table><p>Each of the attributes in <a href="#gkbuk">Table&nbsp;7-7</a> can specify more than one style. If
<tt>columnClasses</tt> or <tt>rowClasses</tt> specifies more than one style, the styles are applied
to the columns or rows in the order that the styles are listed
in the attribute. For example, if <tt>columnClasses</tt> specifies styles <tt>list-column-center</tt> and <tt>list-column-right</tt> and
if the table has two columns, the first column will have style <tt>list-column-center</tt>,
and the second column will have style <tt>list-column-right</tt>.</p>

<p>If the style attribute specifies more styles than there are columns or rows,
the remaining styles will be assigned to columns or rows starting from the
first column or row. Similarly, if the style attribute specifies fewer styles than
there are columns or rows, the remaining columns or rows will be assigned
styles starting from the first style.</p>



<a name="bnaso"></a><h3>Displaying Error Messages with the <tt>h:message</tt> and <tt>h:messages</tt> Tags</h3>
<a name="indexterm-398"></a><a name="indexterm-399"></a><p>The <tt>h:message</tt> and <tt>h:messages</tt> tags are used to display error messages when conversion
or validation fails. The <tt>h:message</tt> tag displays error messages related to a
specific input component, whereas the <tt>h:messages</tt> tag displays the error messages for the entire
page.</p>

<p>Here is an example <tt>h:message</tt> tag from the <tt>guessnumber</tt> application:</p>

<pre>&lt;h:inputText id="userNo" value="#{UserNumberBean.userNumber}">
    &lt;f:validateLongRange minimum="0" maximum="10" />
 &lt;h:commandButton id="submit"
         action="success" value="Submit" />&lt;p>
&lt;h:message
     style="color: red;
     font-family: 'New Century Schoolbook', serif;
     font-style: oblique;
     text-decoration: overline" id="errors1" for="userNo"/></pre><p><a name="indexterm-400"></a>The <tt>for</tt> attribute refers to the ID of the component that generated the
error message. The error message is displayed at the same location that the
<tt>h:message</tt> tag appears in the page. In this case, the error message will
appear after the Submit button.</p>

<p><a name="indexterm-401"></a>The <tt>style</tt> attribute allows you to specify the style of the text of
the message. In the example in this section, the text will be red,
New Century Schoolbook, serif font family, and oblique style, and a line will
appear over the text. The message and messages tags support many other attributes
for defining styles. For more information on these attributes, refer to the documentation
at <a href="http://download.oracle.com/javaee/6/javaserverfaces/2.1/docs/vdldocs/facelets/">http://download.oracle.com/javaee/6/javaserverfaces/2.1/docs/vdldocs/facelets/</a>.</p>

<p>Another attribute supported by the <tt>h:messages</tt> tag is the <tt>layout</tt> attribute. Its default
value is <tt>list</tt>, which indicates that the messages are displayed in a bullet
list using the HTML <tt>ul</tt> and <tt>li</tt> elements. If you set the attribute value
to <tt>table</tt>, the messages will be rendered in a table using the HTML
<tt>table</tt> element.</p>

<p>The preceding example shows a standard validator that is registered on the input
component. The message tag displays the error message that is associated with this
validator when the validator cannot validate the input component&rsquo;s value. In general, when
you register a converter or validator on a component, you are queueing the
error messages associated with the converter or validator on the component. The <tt>h:message</tt>
and <tt>h:messages</tt> tags display the appropriate error messages that are queued on the
component when the validators or converters registered on that component fail to convert
or validate the component&rsquo;s value.</p>

<p>Standard error messages are provided with standard converters and standard validators. An application
architect can override these standard messages and supply error messages for custom converters
and validators by registering custom error messages with the application.</p>



<a name="giqzd"></a><h3>Creating Bookmarkable URLs with the <tt>h:button</tt> and <tt>h:link</tt> Tags</h3>
<a name="indexterm-402"></a><a name="indexterm-403"></a><a name="indexterm-404"></a><a name="indexterm-405"></a><p>The ability to create bookmarkable URLs refers to the ability to generate hyperlinks
based on a specified navigation outcome and on component parameters.</p>

<p>In HTTP, most browsers by default send GET requests for URL retrieval and
POST requests for data processing. The GET requests can have query parameters and
can be cached, which is not advised for POST requests, which send
data to the external servers. The other JavaServer Faces tags capable of generating hyperlinks
use either simple GET requests, as in the case of <tt>h:outputlink</tt>, or
POST requests, as in the case of <tt>h:commandLink</tt> or <tt>h:commandButton</tt> tags. GET
requests with query parameters provide finer granularity to URL strings. These URLs are
created with one or more <tt>name=value</tt> parameters appended to the simple URL
after a <tt>?</tt> character and separated by either <tt>&amp;;</tt> or <tt>&amp;amp;</tt> strings.</p>

<p>To create a bookmarkable URL, use an <tt>h:link</tt> or <tt>h:button</tt> tag. Both
of these tags can generate a hyperlink based on the <tt>outcome</tt> attribute of
the component. For example:</p>

<pre>&lt;h:link outcome="response" value="Message">
  &lt;f:param name="Result" value="#{sampleBean.result}"/>
&lt;/h:link></pre><p>The <tt>h:link</tt> tag will generate a URL link that points to the <tt>response.xhtml</tt>
file on the same server, appended with the single query parameter created by
the <tt>f:param</tt> tag. When processed, the parameter <tt>Result</tt> is assigned the value of the
managed bean&rsquo;s result method <tt>#{sampleBean.result}</tt>. The following sample HTML is generated from the
preceding set of tags, assuming that the value of the parameter is <tt>success</tt>:</p>

<pre>&lt;a href="http://localhost:8080/guessnumber/response.xhtml?Result=success">Response&lt;/a></pre><p>This is a simple GET request. To create more complex GET requests
and utilize the complete functionality of the <tt>h:link</tt> tag, you can use view parameters.</p>



<a name="giqwq"></a><h3>Using View Parameters to Configure Bookmarkable URLs</h3>
<a name="indexterm-406"></a><a name="indexterm-407"></a><p>The core tags <tt>f:metadata</tt> and <tt>f:viewparam</tt> are used as a source of parameters
for configuring the URLs. View parameters are declared as part of <tt>f:metadata</tt> for
a page, as shown in the following example:</p>

<pre>&lt;h:body>
&lt;f:metadata>
  &lt;f:viewParam id="name" name="Name" value="#{sampleBean.username}"/>
  &lt;f:viewParam id="ID" name="uid" value="#{sampleBean.useridentity}"/>
&lt;/f:metadata>
&lt;h:link outcome="response" value="Message" includeViewParams="true">
&lt;/h:link>
&lt;/h:body></pre><p>View parameters are declared with the <tt>f:viewparam</tt> tag and are placed inside the
<tt>f:metadata</tt> tag. If the <tt>includeViewParams</tt> attribute is set on the component, the
view parameters are added to the hyperlink.</p>

<p>The resulting URL will look like this:</p>

<pre>http://localhost:8080/guessnumber/response.xhtml?Name=Duke&amp;;uid=2001</pre><p>Because the URL can be the result of various parameter values, the
order of the URL creation has been predefined. The order in which the
various parameter values are read is as follows:</p>


<ol><li><p>Component</p>

</li>
<li><p>Navigation-case parameters</p>

</li>
<li><p>View parameters</p>

</li></ol>


<a name="gjgep"></a><h3>Resource Relocation Using <tt>h:output</tt> Tags</h3>
<a name="indexterm-408"></a><a name="indexterm-409"></a><p>Resource relocation refers to the ability of a JavaServer Faces application to specify
the location where a resource can be rendered. Resource relocation can be defined
with the following HTML tags:</p>


<ul><li><p><tt>h:outputScript</tt></p>

</li>
<li><p><tt>h:outputStylesheet</tt></p>

</li></ul>
<p>These tags have <tt>name</tt> and <tt>target</tt> attributes, which can be used to define
the render location. For a complete list of attributes for these tags, see
the documentation at <a href="http://download.oracle.com/javaee/6/javaserverfaces/2.1/docs/vdldocs/facelets/">http://download.oracle.com/javaee/6/javaserverfaces/2.1/docs/vdldocs/facelets/</a>.</p>

<p>For the <tt>h:outputScript</tt> tag, the name and target attributes define where the output
of a resource may appear. Here is an example:</p>

<pre>&lt;html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:h="http://java.sun.com/jsf/html">
    &lt;h:head id="head">
        &lt;title>Resource Relocation&lt;/title>
    &lt;/h:head>
    &lt;h:body id="body">
        &lt;h:form id="form">        
            &lt;h:outputScript name="hello.js"/>
            &lt;h:outputStylesheet name="hello.css"/>
        &lt;/h:form>
    &lt;/h:body>
&lt;/html></pre><p>Since the <tt>target</tt> attribute is not defined in the tag, the style sheet
<tt>hello.css</tt> is rendered in the head, and the <tt>hello.js</tt> script is rendered in
the body of the page as defined by the <tt>h:head</tt> tag.</p>

<p>Here is the HTML generated by the preceding code:</p>

<pre>&lt;html xmlns="http://www.w3.org/1999/xhtml">
    &lt;head>
        &lt;title>Resource Relocation&lt;/title>
        &lt;link type="text/css" rel="stylesheet"
              href="/ctx/faces/javax.faces.resource/hello.css"/>
    &lt;/head>
    &lt;body>
        &lt;form id="form" name="form" method="post" action="..." enctype="...">
            &lt;script type="text/javascript"
             src="/ctx/faces/javax.faces.resource/hello.js">
            &lt;/script>
        &lt;/form>
    &lt;/body>
&lt;/html></pre><p>The original page can be recreated by setting the <tt>target</tt> attribute for the
<tt>h:outputScript</tt> tag, which allows the incoming GET request to provide the location parameter.
Here is an example:</p>

<pre>&lt;html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:h="http://java.sun.com/jsf/html">
    &lt;h:head id="head">
        &lt;title>Resource Relocation&lt;/title>
    &lt;/h:head>
    &lt;h:body id="body">
        &lt;h:form id="form">        
            &lt;h:outputScript name="hello.js" target="#{param.location}"/>
            &lt;h:outputStylesheet name="hello.css"/>
        &lt;/h:form>
    &lt;/h:body>
&lt;/html></pre><p>In this case, if the incoming request does not provide a location
parameter, the default locations will still apply: The style sheet is rendered in
the head, and the script is rendered inline. However, if the incoming request provides
the location parameter as the head, both the style sheet and the script
will be rendered in the head element.</p>

<p>The HTML generated by the preceding code is as follows:</p>

<pre>&lt;html xmlns="http://www.w3.org/1999/xhtml">
    &lt;head>
        &lt;title>Resource Relocation&lt;/title>
        &lt;link type="text/css" rel="stylesheet"
              href="/ctx/faces/javax.faces.resource/hello.css"/>
          &lt;script type="text/javascript"
           src="/ctx/faces/javax.faces.resource/hello.js">
          &lt;/script>
    &lt;/head>
    &lt;body>
        &lt;form id="form" name="form" method="post" action="..." enctype="...">
        &lt;/form>
    &lt;/body>
&lt;/html></pre><p>Similarly, if the incoming request provides the location parameter as the body, the
script will be rendered in the body element.</p>

<p>The preceding section describes simple uses for resource relocation. That feature can add
even more functionality for the components and pages. A page author does not
have to know the location of a resource or its placement.</p>

<p>By using a <tt>@ResourceDependency</tt> annotation for the components, component authors can define the
resources for the component, such as a style sheet and script. This allows
the page authors freedom from defining resource locations.</p>


         </div>
         <div class="navigation">
             <a href="bnarb.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="bnarc.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

